feat(agents): add AgentEnvironment / EnvironmentSpec / ComputeSpec entities - #1379

- deployments.py: return 422 (not 400) for EnvironmentResolutionError — the
  request is syntactically valid but references an environment/spec that
  cannot be resolved (semantic error).
- entities.py/agent_config.py: drop internal RFC-122/RFC122 identifiers from
  shipped source comments/docstrings; keep the descriptive text.
- entities.py: rename EnvironmentSpec field artifacts -> artifacts_path for
  symmetry with workspace_path; environment_resolution.py maps it onto the
  config's environment.artifacts (mirroring the workspace_path -> workspace
  mapping), so the Fabric-facing field name is unchanged.
- Regenerate the agents plugin OpenAPI spec: adds the AgentEnvironment /
  EnvironmentSpec / ComputeSpec schemas + routes (previously not regenerated)
  and reflects the artifacts_path rename.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

Permission-id segments must match [a-z0-9]+(-[a-z0-9]+)* (no underscores);
the EnvironmentSpec/ComputeSpec PermissionSets used underscored namespaces
(agents.environment_specs / agents.compute_specs), which the authz bundle
rejected as malformed permission ids and failed closed (hard_fail), 500ing
the auth service and breaking platform startup in tests.

Rename the namespaces to agents.environment-specs / agents.compute-specs
(matching the hyphenated route paths). Covered by the existing
plugins/nemo-agents/tests/test_authz.py derivation assertion (problems == []).

Signed-off-by: Ben McCown <bmccown@nvidia.com>

- deployments.py: type _resolve_deployment_environment's environment param
  as str | AgentEnvironmentInline | None (was Any) to match the request
  contract and restore type checking at that boundary.
- environments.py/test: add concrete type hints (NemoEntitiesClient, bounded
  TypeVars for entity/page/filter) to the shared CRUD helpers and to the
  _stamp test helper so ty checks them.
- environment_resolution.py (_merge_mcp): only fulfill MCP servers the Agent
  declared; skip fulfillments for undeclared server names (request/fulfill
  contract) so an environment cannot inject unrequested MCP servers.
- Preserve EnvironmentSpec secret references (previously dropped): snapshot
  them onto AgentDeployment.secrets and compile them into secret-backed
  container env vars (EnvVar.secret_ref, never plaintext), threaded through
  the controller/backend like the compute snapshot. The deployments-plugin
  substrate materializes/mounts them (docker plaintext env, k8s managed
  Secret via envFrom). Subprocess mode ignores them.
- Regenerate the agents OpenAPI spec for the new AgentDeployment.secrets field.

Adds coverage for undeclared-MCP skipping, secret snapshotting on create, and
secret_ref env-var compilation.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

…r vars

A secret env var from the environment whose name matches a platform-generated
container env var (NMP_WORKSPACE, NMP_AGENT_NAME, NMP_BASE_URL,
AGENT_CONFIG_PATH, NAT_CONFIG_PATH) behaves inconsistently across substrates:
docker applies the secret value over the generated one, while k8s ignores the
colliding secret because explicit env entries take precedence over the managed
Secret's envFrom. Reject the collision at compile time (ReservedSecretEnvVarError,
surfaced as a failed deployment) instead of silently shadowing platform wiring.

Adds docker + k8s coverage for each reserved name.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

PYTHONPATH is injected on the agent container in the k8s plugin-wheels path.
Add it to the reserved env var names (unconditionally, so the guard is
mode-independent) so an environment secret named PYTHONPATH is rejected up
front rather than silently shadowed. Extend the docker+k8s collision test.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

…secret compiler

Two correctness fixes in the EnvironmentSpec merge:

1. provider clobber: EnvironmentSpecInline.provider defaults to "local" (non-None),
   so the flipped precedence overwrote an Agent's explicit "docker"/"k8s" with
   "local" even when the spec never set provider. Only override a scalar mirror
   field when the spec EXPLICITLY set it (model_fields_set), not on schema
   defaults.

2. MCP secrets were stored as plaintext: _merge_mcp put McpFulfillment.secrets
   (which are ENV_NAME -> secret refs) directly into mcp.servers.<name>.env as
   literal values, so the raw reference leaked into agent.yaml and the secret was
   never resolved. Route both top-level and per-MCP secrets through a single
   collected secrets map that merge_environment_spec_into_agent_config now
   returns (MergedEnvironment). The deployment snapshots that map so the substrate
   injects the resolved value into the process env under ENV_NAME (secret_ref,
   never plaintext); MCP servers read their credentials from the process env by
   name (env-var-name indirection, per Fabric guidance). Only non-secret MCP env
   is written into the server config.

Conflicting refs for the same env var name raise EnvironmentResolutionError
(surfaced as 422). Adds tests for the provider guard, MCP secret collection (not
in config), and ref conflicts.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

The secret collector only detected secret-vs-secret ref conflicts. A name could
still be bound both as a secret (injected as a secret_ref env var) and as a
plaintext value in the merged environment.env or a declared MCP server's env, so
the effective credential depended on runtime env construction order.

Add a validation pass that rejects (EnvironmentResolutionError -> 422) any
collected secret name that also appears as a plaintext binding in
environment.env or any mcp.servers.<name>.env. Covers plaintext from the Agent
config as well as the spec. Adds top-level, agent-plaintext, and MCP regression
tests.

Signed-off-by: Ben McCown <bmccown@nvidia.com>